Перенос системы документооборота на новую Ubuntu

Версия: 1.1 Дата: 26.04.2026 Статус: Утверждён

Руководство описывает полный перенос системы документооборота (Docusaurus + Decap CMS + Tools API + автокоммит) на чистую Ubuntu-машину. Все настройки и наработки сохраняются без потерь.

Изменения в v1.1 (26.04.2026): в систему добавлен четвёртый pm2-процесс cms-auto-commit — наблюдатель, делающий автоматический git-коммит при правке любого .md/.json в docs/ через 60 секунд тишины. Все шаги переноса обновлены: добавлена системная зависимость inotify-tools (шаг 3), запуск четырёх процессов вместо трёх (шаг 6), запуск через ecosystem.config.js вместо отдельных pm2 start, четыре строки в чеклисте и диагностике. Подробности про автокоммит — в Автокоммит CMS — настройка и поведение.

Что входит в систему

Компонент	Описание
`~/sites/cms-docs/`	Весь проект: документация, конфиги, инструменты
Node.js 24 (через nvm)	Среда выполнения
pm2	Менеджер процессов, автозапуск четырёх сервисов
`inotify-tools`	Системная зависимость для `cms-auto-commit` (наблюдатель `inotifywait` за `docs/`)
inkscape + imagemagick	Конвертация SVG → JPEG/PNG (опционально)
SSH-ключи	Для деплоя на VPS и shared-хостинг

Шаг 1. Установить Node.js через nvm

На новой машине не устанавливать Node.js через apt — только через nvm, иначе pm2 не будет видеть правильный путь к node.

# Установить nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Перезагрузить окружение
source ~/.bashrc

# Минимальная версия — Node.js 20, рекомендуется фиксировать конкретный LTS-релиз
# (тот под которым установлен pm2 — например 24.14.1)
nvm install 24.14.1
nvm use 24.14.1
nvm alias default 24.14.1

# Проверить
node --version   # должно быть v24.14.1
npm --version

Шаг 2. Установить pm2 глобально

pm2 управляет тремя процессами системы и поднимает их при перезагрузке машины.

npm install -g pm2

# Проверить
pm2 --version

Шаг 3. Установить системные инструменты

# rsync — для деплоя на серверы
sudo apt install -y rsync

# inotify-tools — для процесса cms-auto-commit (наблюдатель за docs/)
# Без него четвёртый pm2-процесс не запустится
sudo apt install -y inotify-tools

# Inkscape и ImageMagick — для конвертации SVG → JPEG/PNG
# Нужны только если используется функция конвертации диаграмм
sudo apt install -y inkscape imagemagick

# Проверить версии
which inotifywait      # ожидаем /usr/bin/inotifywait
inkscape --version     # должно быть 1.x
convert --version      # ImageMagick

Шаг 4. Скопировать проект

Проект переносится целиком — все настройки, скрипты, документы, node_modules.

Вариант А: через rsync по SSH (если машины в сети)

# Выполнить со старой машины
rsync -az --progress \
  --exclude='.git' \
  --exclude='build' \
  --exclude='.docusaurus' \
  ~/sites/cms-docs/ \
  user@newmachine:~/sites/cms-docs/

Вариант Б: через архив

# На старой машине — упаковать
tar -czf cms-docs-backup.tar.gz \
  --exclude='./sites/cms-docs/.git' \
  --exclude='./sites/cms-docs/build' \
  --exclude='./sites/cms-docs/.docusaurus' \
  -C ~/ sites/cms-docs/

# Скопировать архив на новую машину
scp cms-docs-backup.tar.gz user@newmachine:~/

# На новой машине — распаковать
mkdir -p ~/sites
tar -xzf cms-docs-backup.tar.gz -C ~/

node_modules включать в архив или нет? Включать — надёжнее, не нужно ждать npm install. Исключить если хочется чистую установку зависимостей. Если исключили — после распаковки выполнить cd ~/sites/cms-docs && npm install.

Шаг 5. Скопировать SSH-ключи для деплоя

Ключи хранятся в ~/.ssh/ и не входят в проект намеренно.

# Посмотреть какие ключи используются в проекте
grep ssh_key ~/sites/cms-docs/cms-config.json

# Скопировать нужные ключи (пример)
scp ~/.ssh/vps-vlad user@newmachine:~/.ssh/
scp ~/.ssh/vps-vlad.pub user@newmachine:~/.ssh/

# На новой машине — выставить правильные права
chmod 600 ~/.ssh/vps-vlad
chmod 644 ~/.ssh/vps-vlad.pub

Если используется ~/.ssh/config с алиасами хостов — скопировать и его:

scp ~/.ssh/config user@newmachine:~/.ssh/config

Шаг 6. Запустить процессы через pm2

Четыре процесса которые должны работать постоянно:

Имя процесса	Что делает	Порт
`cms-docs-dev`	Docusaurus dev-сервер	3000
`cms-decap-server`	Прокси-бэкенд для Decap CMS — пишет файлы при Publish из CMS	8083
`cms-tools-api`	API панели управления `tools.html` — деплой, конвертация SVG, управление пользователями	8084
`cms-auto-commit`	Наблюдатель `inotifywait` за `docs/` — автоматический `git commit` через 60 сек тишины. Подробности — в Автокоммит CMS — настройка и поведение	—

Запуск через единый конфиг (он уже скопирован вместе с проектом в шаге 4 — файл ecosystem.config.js в корне):

cd ~/sites/cms-docs

# Запустить все четыре процесса одной командой
pm2 start ecosystem.config.js

# Проверить статус — все четыре должны быть online
pm2 list

# Сохранить список процессов для автозапуска
pm2 save

Ожидаемый вывод pm2 list:

┌────┬──────────────────────┬─────────┬──────────┬──────────┐
│ id │ name                 │ status  │ cpu      │ mem      │
├────┼──────────────────────┼─────────┼──────────┼──────────┤
│ 0  │ cms-docs-dev         │ online  │ 0%       │ 72mb     │
│ 1  │ cms-decap-server     │ online  │ 0%       │ 92mb     │
│ 2  │ cms-tools-api        │ online  │ 0%       │ 65mb     │
│ 3  │ cms-auto-commit      │ online  │ 0%       │ 3mb      │
└────┴──────────────────────┴─────────┴──────────┴──────────┘

Если cms-auto-commit упал сразу после запуска — самая частая причина пропущенный inotify-tools. Решение:

sudo apt install -y inotify-tools
pm2 restart cms-auto-commit

Подробное описание ecosystem.config.js — в Руководство по установке Docusaurus + Decap CMS, раздел «Автозапуск через pm2».

Шаг 7. Настроить автозапуск pm2 при перезагрузке

pm2 startup

pm2 выведет команду вида:

sudo env PATH=$PATH:/home/alex/.nvm/versions/node/v24.14.1/bin \
  /home/alex/.nvm/versions/node/v24.14.1/lib/node_modules/pm2/bin/pm2 \
  startup systemd -u alex --hp /home/alex

WSL / Windows-пути в PATH: команда с sudo env PATH=$PATH:... падает с ошибкой env: 'Files': No such file or directory — Windows-пути с пробелами (Program Files) ломают env. Также pm2 внутри вызывает env node, которого нет в системном PATH sudo.

Вместо этого выполнить два шага:

# 1. Создать симлинк на node для sudo
sudo ln -sf /home/alex/.nvm/versions/node/v24.14.1/bin/node /usr/local/bin/node

# 2. Запустить startup напрямую без env PATH=
sudo /home/alex/.nvm/versions/node/v24.14.1/lib/node_modules/pm2/bin/pm2 startup systemd -u alex --hp /home/alex

Затем сохранить список процессов:

pm2 save

Важно: пути в команде содержат конкретную версию node. Выполнять на новой машине после того как pm2 установлен — не копировать со старой.

Шаг 8. Проверить конфиг cms-config.json

Открыть ~/sites/cms-docs/cms-config.json и проверить пути:

cat ~/sites/cms-docs/cms-config.json

Что может потребовать правки:

Поле	Что проверить
`vps.ssh_key`	Путь к SSH-ключу существует на новой машине
`shared.ssh_key`	Аналогично
`vps.ssh_host`	Хост VPS — не меняется
`vps.remote_path`	Путь на VPS — не меняется

Шаг 9. Проверить работу системы

# Все процессы запущены
pm2 list

# Docusaurus открывается
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
# Должно вернуть: 200

# Decap-сервер отвечает
curl -s -o /dev/null -w "%{http_code}" http://localhost:8083/api/v1
# Должно вернуть: 404 (нормально — proxy не поддерживает GET)

# Tools API отвечает
curl -s http://localhost:8084/projects
# Должно вернуть список проектов в JSON

Открыть в браузере:

http://localhost:3000 — сайт документации
http://localhost:3000/admin/ — CMS редактор
http://localhost:3000/admin/tools.html — панель управления

Готовый снапшот системы

Снапшот — архив всего необходимого для переноса одним действием. Создаётся на старой машине, распаковывается на новой поверх домашней директории.

Создать снапшот (на старой машине)

# Сохранить текущий список pm2 процессов
pm2 save

# Создать папку архивов
mkdir -p ~/archives

# Создать структуру путей
mkdir -p ~/archives/cms-system/home/alex/sites/cms-docs \
         ~/archives/cms-system/home/alex/.ssh \
         ~/archives/cms-system/home/alex/.pm2

# Скопировать проект (без build, .git, .docusaurus)
rsync -az \
  --exclude='.git' \
  --exclude='build' \
  --exclude='.docusaurus' \
  ~/sites/cms-docs/ \
  ~/archives/cms-system/home/alex/sites/cms-docs/

# Скопировать SSH-ключи
cp ~/.ssh/vps-vlad  ~/archives/cms-system/home/alex/.ssh/
cp ~/.ssh/vps-vlad.pub ~/archives/cms-system/home/alex/.ssh/
cp ~/.ssh/config    ~/archives/cms-system/home/alex/.ssh/

# Скопировать pm2 dump
cp ~/.pm2/dump.pm2  ~/archives/cms-system/home/alex/.pm2/

# Упаковать
cd ~/archives && tar -czf cms-system-snapshot-$(date +%Y%m%d).tar.gz cms-system/

# Проверить размер
ls -lh ~/archives/cms-system-snapshot-*.tar.gz

Структура архива

cms-system-snapshot-YYYYMMDD.tar.gz
└── cms-system/
    └── home/
        └── alex/
            ├── sites/
            │   └── cms-docs/          ← весь проект с node_modules
            ├── .ssh/
            │   ├── vps-vlad           ← приватный SSH-ключ для деплоя
            │   ├── vps-vlad.pub
            │   └── config             ← алиасы хостов
            └── .pm2/
                └── dump.pm2           ← список pm2 процессов для восстановления

Распаковать на новой машине

# Распаковать от корня — всё ляжет по местам
tar -xzf cms-system-snapshot-20260422.tar.gz -C /

# Выставить права на SSH-ключ
chmod 600 ~/.ssh/vps-vlad

После распаковки выполнить шаги 1–3 (nvm, pm2, inkscape) и шаги 6–7 (запуск процессов и автостарт).

Быстрый чеклист

Диагностика

pm2 процесс падает при старте

# Посмотреть логи
pm2 logs cms-docs-dev --lines 50

# Частая причина: node_modules не установлены
cd ~/sites/cms-docs && npm install

CMS показывает ошибку подключения к backend

# Проверить что decap-server запущен
pm2 logs cms-decap-server --lines 20

# Проверить порт
ss -tlnp | grep 8083

Деплой на VPS не работает

# Проверить SSH-ключ
ssh -o BatchMode=yes -i ~/.ssh/vps-vlad -p 22 vlad@85.214.181.52 "echo ok"

# Если ошибка — ключ не скопирован или неверные права
chmod 600 ~/.ssh/vps-vlad

cms-auto-commit падает или не делает коммиты

Симптом 1. Процесс падает сразу при старте, статус errored.

# Посмотреть лог
pm2 logs cms-auto-commit --lines 30

Самая частая причина — не установлен inotify-tools:

which inotifywait || sudo apt install -y inotify-tools
pm2 restart cms-auto-commit

Симптом 2. Процесс online, но правки в docs/ не попадают в git log.

# Создать тестовый файл и проверить через 90 сек
echo "test" > docs/test-auto-commit.md
sleep 70
git log --oneline -3 | head -3
rm docs/test-auto-commit.md

В логе должны появиться события CREATE и через 60 сек строка коммит: 1 файлов:

tail -20 ~/.pm2/logs/cms-auto-commit-out.log

Если в логе нет событий — наблюдатель не получает их (бывает в WSL при правках через Windows-редактор по сетевому пути). Решение: править через Linux-инструменты или через CMS.

Симптом 3. Watcher делает коммиты слишком часто или коммитит мусор.

Можно временно остановить:

pm2 stop cms-auto-commit       # пауза на массовые ручные правки
# … работа …
pm2 start cms-auto-commit      # вернуть после

Подробности — в Автокоммит CMS — настройка и поведение.

Что входит в систему​

Шаг 1. Установить Node.js через nvm​

Шаг 2. Установить pm2 глобально​

Шаг 3. Установить системные инструменты​

Шаг 4. Скопировать проект​

Вариант А: через rsync по SSH (если машины в сети)​

Вариант Б: через архив​

Шаг 5. Скопировать SSH-ключи для деплоя​

Шаг 6. Запустить процессы через pm2​

Шаг 7. Настроить автозапуск pm2 при перезагрузке​

Шаг 8. Проверить конфиг cms-config.json​

Шаг 9. Проверить работу системы​

Готовый снапшот системы​

Создать снапшот (на старой машине)​

Структура архива​

Распаковать на новой машине​

Быстрый чеклист​

Диагностика​

pm2 процесс падает при старте​

CMS показывает ошибку подключения к backend​

Деплой на VPS не работает​

cms-auto-commit падает или не делает коммиты​